Модуль PKIProxy
-----------------

Общие сведения
^^^^^^^^^^^^^^^^

**PKIProxy** — модуль, разворачиваемый на одном или более Контроллерах домена, предназначенный для управления сертификатами в рамках доменной инфраструктуры, используя только протоколы **Kerberos** и **LDAP**.

Архитектура и функции компонентов
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Компоненты и их функции
'''''''''''''''''''''''''

-  Сервис ``aldpro-pkiproxy-service`` - обеспечивает чтение запросов на: управление сертификатами (выпуск, отзыв и т.д.) и регистрации новых удостоверяющих центров (УЦ). Предоставляет унифицированный интерфейс для плагинов УЦ (``pkiproxy-plugins``).

-  Плагины ``pkiproxy-plugins`` - используя стандартный (унифицированный) интерфейс ``pkiproxy`` реализуют базовые функции управления сертификатами (выпуск, отзыв и т.д.).

-  Интерфейс командной строки (cli):

   -  ``pkiproxy-cli`` - управления сертификатами принципала;

   -  ``regca`` - регистрация УЦ с определённым плагином (по умолчанию - ``caless``).

Общая схема работы
''''''''''''''''''''''''

Запросы на операции с сертификатами формируются на стороне клиента и записываются в **LDAP**. В качестве клиента может выступать любой клиент домена, требующий наличия сертификата. **LDAP** используется для передачи запросов и получения результатов обработки, а также для хранения конфигурации модуля.

Обработка запросов выполняется контроллерами домена с ролью **PKIProxy**. Сервис **PKIProxy** запускается с заданной периодичностью и вычитывает ожидающие обработки запросы из **LDAP**. Для каждого запроса сервис определяет тип требуемой операции и параметры обработки, после чего инициирует взаимодействие с УЦ с использованием плагина с которым УЦ был зарегистрирован.

Результат обработки запроса записывается в атрибут **LDAP**. После успешной обработки соответствующий запрос удаляется. Клиентская сторона опрашивает **LDAP** и получает результат обработки по мере его появления.

Такой подход позволяет выполнять операции с сертификатами даже в сценариях, когда запрашивающий узел не имеет прямой сетевой доступности до контроллера домена с ролью **PKIProxy**.

.. figure:: images/image1.png
   :name: work_schema

   Схема работы **PKIProxy**

Установка и настройка PKIProxy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Назначение роли **PKIProxy** выполняется через Портал управления **ALD Pro** в соответствии с порядком, описанным в **Руководстве администратора, часть 1**.

Установка PKIProxy на первом контроллере домена
'''''''''''''''''''''''''''''''''''''''''''''''''''

При чистой установке **ALD Pro** версии 3.2.0 и выше модуль **PKIProxy** инициализируется автоматически при назначении роли **PKIProxy** первому контроллеру домена.

В процессе инициализации:

-  запускается сервис **PKIProxy**;

-  автоматически регистрируется УЦ **default-caless**.

Дополнительные действия администратора не требуются.

Установка PKIProxy на дополнительном контроллере домена
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Назначение роли **PKIProxy** дополнительному контроллеру домена выполняется через Портал управления **ALD Pro**. Порядок назначения роли и требования к предварительной подготовке контроллера домена описаны в разделе «Установка и инициализация **PKIProxy**».

После назначения роли сервис **PKIProxy** инициализируется автоматически, однако регистрация УЦ автоматически не выполняется.

Для регистрации удостоверяющего центра на дополнительном контроллере домена необходимо перенести (скопировать) с первого контроллера домена файлы:

-  ``/etc/ssl/freeipa/ca.crt``

-  ``/etc/ssl/freeipa/ca.key``

Перед выполнением регистрации необходимо получить **Kerberos**-билет (выполнить ``kinit admin``). Далее выполнить регистрацию УЦ:

.. code-block:: bash

   /opt/rbta/venvs/aldpro-common/bin/python3 /usr/sbin/regca reg-ca \
    --ca-name default-caless \
    --ca-host $(hostname) \
    --pkiproxy-host $(hostname) \
    --templates kdc,default_caless_template \
    --plugin pkipp-aldpro-caless \
    --pkipp-ca-init-crt-path /etc/ssl/freeipa/ca.crt \
    --pkipp-ca-init-key-path /etc/ssl/freeipa/ca.key \
    --default
   
Выпуск сертификатов
^^^^^^^^^^^^^^^^^^^^^^^

Запрос на выпуск сертификата формируется клиентской частью и записывается в **LDAP**. Сервис **PKIProxy** обрабатывает запросы с периодичностью 5 минут.

Клиент ожидает появления результата обработки в **LDAP**. Максимальное время ожидания результата составляет до 60 минут с учётом репликации **LDAP** и выполнения операции со стороны УЦ.

Полученный сертификат сохраняется клиентом в файл или в атрибут **LDAP**.

Формирование запроса на сертификат с использованием pkiproxy_cli
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Для формирования запроса на выпуск сертификата (**CSR**) может использоваться утилита командной строки pkiproxy_cli.

Команды ``pkiproxy_cli`` выполняются от пользователя с правами ``root``.

Утилита ``pkiproxy_cli`` позволяет:

-  сформировать записать **CSR** в **LDAP**;

-  сохранить сертификат после выпуска в файл или **LDAP**;

-  просмотреть список зарегистрированных в домене удостоверяющих центров;

-  просмотреть список доступных шаблонов и их параметры.

Просмотр зарегистрированных удостоверяющих центров:

.. code-block:: bash

   pkiproxy_cli show-cas

Список доступных шаблонов:

.. code-block:: bash

   pkiproxy_cli show-templates

Получение детальной информации о параметрах шаблона:

.. code-block:: bash

   pkiproxy_cli template-details --ca <имя_УЦ> --template "<имя_шаблона>"

Формирование **CSR** выполняется командой ``create-csr``. **CSR** может быть сформирован:

-  путём передачи параметров командной строки;

-  либо на основе **JSON**-файла шаблона.

Использование сертификатов для безопасной передачи учетных данных
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

На контроллерах домена вместе с ролью **PKIProxy** назначается роль транспорта паролей (сервис Транспорта паролей, далее Сервис), которая обеспечивает безопасную передачу служебных паролей (**PostgreSQL**, **RabbitMQ** и др.) для узлов с установленными подсистемами. Сервис работает в автоматическом режиме и не требует ручных настроек при штатной работе всех Контроллеров домена.

Процесс работы выполняется следующим образом:

1. Клиент домена генерирует пару ключей (закрытый и открытый) и формирует запрос на выпуск сертификата (**CSR**);

2. **CSR** передается в **LDAP** и обрабатывается Сервис;

3. Сервис выпускает сертификат и сохраняет его в **LDAP**;

4. Сервис использует публичный ключ сертификата для упаковки учетных данных;

5. Упакованные данные сохраняются в атрибуте **LDAP** ``aldproSubsystemVaultCredentials`` объекта клиента домена;

6. Клиент домена получает данные и распаковывает их с использованием закрытого ключа.

Таким образом, передача учетных данных выполняется безопасным образом, а закрытые ключи не покидают пределы устройства (клиента домена), на котором были созданы.

Удаление PKIProxy
^^^^^^^^^^^^^^^^^^^^^^

Для удаления **PKIProxy** необходимо:

-  удалить или перенести УЦ;

-  деактивировать роль **PKIProxy**;

-  остановить и отключить сервисы **PKIProxy**;

-  удалить конфигурацию подсистемы и локальные артефакты УЦ (``/var/lib/pkiproxy/...``).

.. figure:: images/image2.png
   :name: pki_delete_schema

   Схема удаления **PKIProxy**

Проверка состояния сервисов и журналы событий PKIProxy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 Сервис управляется двумя основными ``unit``-файлами, статус которых можно посмотреть командами:

.. code-block:: bash

   systemctl status aldpro-pkiproxy.timer
   systemctl status aldpro-pkiproxy.service
   
Таймер и сервис должны быть включены и не должны содержать ошибок запуска.

Журналы сервиса PKIProxy
''''''''''''''''''''''''''''

Основной журнал подсистемы **PKIProxy** расположен по пути:

.. code-block:: text

   /var/log/pkiproxy/pkiproxy.log

В нём фиксируются события запуска сервиса, подключения к **LDAP** и обработки запросов.

Журналы плагинов удостоверяющих центров

Плагины удостоверяющих центров ведут собственные журналы работы, которые находятся в ``/var/log/pkiproxy/<имя принципала>.<имя плагины>``.

Для плагина ``pkipp-aldpro-caless``:

- журнал операций выпуска сертификатов:

.. code-block:: text

  /var/log/pkiproxy/pkipp-aldpro-caless.log

- журналы операций выпуска сертификатов для отдельных хостов:

.. code-block:: text

  /var/log/pkiproxy/<fqdn>.pkipp-aldpro-caless.log

